Documentation Version for Comments and Changes

You are invited to make any changes...add any comments.

Changes will `eventually` be merged into the offical documentation.

Leave any commnents here...

...

... back to index page OE documentation

The User Defined Pre-Processor

The user defined pre-processor, developed by Jeremy Cowgar, opens a world of possibilities to the Euphoria programmer. In a sentence, it allows one to create (or use) a translation process that occurs transparently when a program is run. This mini-guide is going to explore the pre-processor interface by first giving a quick example, then explaining it in detail and finally by writing a few useful pre-processors that can be put immediately to work.

Any program can be used as a pre-processor. It must, however, adhere to a simple specification:

1. Accept a parameter "-i filename" which specifies which file to read and process.
2. Accept a parameter "-o filename" which specifies which file to write the result to.
3. Exit with a zero error code on success or a non-zero error code on failure.

It does not matter what type of program it is. It can be a Euphoria script, an executable written in the C programming language, a script/batch file or anything else that can read one file and write to another file. As Euphoria programmers, however, we are going to focus on writing pre-processors in the Euphoria programming language. As a benefit, we will describe later on how you can easily convert your pre-processor to a shared library that Euphoria can make use of directly thus improving performance.

A Quick Example

The problem in this case is that you want the copyright statement and the about screen to show what date the program was compiled on but you do not want to manually maintain this date. So, we are going to create a simple pre-processor that will read a source file, replace all instances of @DATE@ with the current date and then write the output back out.

Before we get started, let me say that we will expand on this example later on. Up front, we are going to do almost no error checking for the purpose of showing off the pre-processor not for the sake of making a production quality application.

We are going to name this file datesub.ex.

-- datesub.ex 
include std/datetime.e -- now() and format() 
include std/io.e       -- read_file() and write_file() 
include std/search.e   -- match_replace() 
 
sequence cmds = command_line() 
sequence inFileName, outFileName 
 
for i = 3 to length(cmds) do 
    switch cmds[i] do 
        case "-i" then 
            inFileName = cmds[i+1] 
        case "-o" then 
            outFileName = cmds[i+1] 
    end switch 
end for 
 
sequence content = read_file(inFileName) 
 
content = match_replace("@DATE@", content, format(now())) 
 
write_file(outFileName, content) 
 
-- programs automatically exit with ZERO error code, if you want 
-- non-zero, you exit with abort(1), for example.